home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / library.n < prev    next >
Text File  |  1994-09-20  |  10KB  |  265 lines
  1.  
  2.  
  3.  
  4. library(n)            Tcl Built-In Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      library - standard library of Tcl procedures
  12.  
  13. SYNOPSIS
  14.      auto_execok _c_m_d
  15.      auto_load _c_m_d
  16.      auto_mkindex _d_i_r _p_a_t_t_e_r_n _p_a_t_t_e_r_n ...
  17.      auto_reset
  18.      parray _a_r_r_a_y_N_a_m_e
  19.      unknown _c_m_d ?_a_r_g _a_r_g ...?
  20. _________________________________________________________________
  21.  
  22.  
  23. INTRODUCTION
  24.      Tcl includes a library of Tcl procedures for commonly-needed
  25.      functions.   The  procedures  defined in the Tcl library are
  26.      generic ones suitable for use  by  many  different  applica-
  27.      tions.   The  location of the Tcl library is returned by the
  28.      info library command.  In addition to the Tcl library,  each
  29.      application  will  normally  have its own library of support
  30.      procedures as well;  the location of this  library  is  nor-
  31.      mally  given  by  the value of the $_a_p_p_library global vari-
  32.      able, where _a_p_p is the name of the application.   For  exam-
  33.      ple,  the location of the Tk library is kept in the variable
  34.      $tk_library.
  35.  
  36.      To access the procedures in the Tcl library, an  application
  37.      should  source the file init.tcl in the library, for example
  38.      with the Tcl command
  39.  
  40.           source [info library]/init.tcl
  41.  
  42.      This will define the unknown procedure and arrange  for  the
  43.      other  procedures to be loaded on-demand using the auto-load
  44.      mechanism defined below.
  45.  
  46.  
  47. COMMAND PROCEDURES
  48.      The following procedures are provided in the Tcl library:
  49.  
  50.      auto_execok _c_m_d
  51.           Determines whether there is an executable file  by  the
  52.           name _c_m_d.  This command examines the directories in the
  53.           current search path  (given  by  the  PATH  enviornment
  54.           variable)  to  see if there is an executable file named
  55.           _c_m_d in any of those directories.  If so, it returns  1;
  56.           if  not  it returns 0.  Auto_exec remembers information
  57.           about previous searches in an array  named  auto_execs;
  58.           this  avoids  the  path  search in future calls for the
  59.           same _c_m_d.  The command auto_reset may be used to  force
  60.           auto_execok to forget its cached information.
  61.  
  62.  
  63.  
  64. Tcl                                                             1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. library(n)            Tcl Built-In Commands
  71.  
  72.  
  73.  
  74.      auto_load _c_m_d
  75.           This command attempts to load the definition for a  Tcl
  76.           command  named  _c_m_d.   To do this, it searches an _a_u_t_o-
  77.           _l_o_a_d _p_a_t_h, which is a list of one or more  directories.
  78.           The  auto-load  path  is  given  by the global variable
  79.           $auto_path if it exists.  If  there  is  no  $auto_path
  80.           variable,  then  the TCLLIBPATH environment variable is
  81.           used, if it exists.  Otherwise the auto-load path  con-
  82.           sists  of  just the Tcl library directory.  Within each
  83.           directory in the auto-load path there must  be  a  file
  84.           tclIndex that describes one or more commands defined in  |
  85.           that directory and a script to evaluate to load each of  |
  86.           the  commands.   The  tclIndex file should be generated  |
  87.           with the auto_mkindex command.  If _c_m_d is found  in  an  |
  88.           index file, then the appropriate script is evaluated to  |
  89.           create the command.  The auto_load command returns 1 if
  90.           _c_m_d was successfully created.  The command returns 0 if
  91.           there was no index entry  for  _c_m_d  or  if  the  script
  92.           didn't actually define _c_m_d (e.g. because index informa-
  93.           tion is out of date).  If an error  occurs  while  pro-
  94.           cessing  the  script,  then  that  error  is  returned.
  95.           Auto_load only reads the  index  information  once  and
  96.           saves  it  in  the  array  auto_index;  future calls to
  97.           auto_load check for _c_m_d in the array  rather  than  re-
  98.           reading  the index files.  The cached index information
  99.           may be deleted with the command auto_reset.  This  will
  100.           force  the  next  auto_load command to reload the index
  101.           database from disk.
  102.  
  103.      auto_mkindex _d_i_r _p_a_t_t_e_r_n _p_a_t_t_e_r_n ...
  104.           Generates an index suitable for use by auto_load.   The  |
  105.           command  searches  _d_i_r  for all files whose names match  |
  106.           any of the _p_a_t_t_e_r_n arguments (matching is done with the
  107.           glob  command),  generates an index of all the Tcl com-
  108.           mand procedures defined in all the matching files,  and
  109.           stores  the  index information in a file named tclIndex
  110.           in _d_i_r.  For example, the command
  111.  
  112.                auto_mkindex foo *.tcl
  113.  
  114.  
  115.           will read all the .tcl files in  subdirectory  foo  and
  116.           generate a new index file foo/tclIndex.
  117.  
  118.           Auto_mkindex parses the Tcl  scripts  in  a  relatively
  119.           unsophisticated  way:   if  any  line contains the word
  120.           proc as its first characters then it is assumed to be a
  121.           procedure  definition  and the next word of the line is
  122.           taken as the procedure's name.   Procedure  definitions
  123.           that  don't  appear  in this way (e.g. they have spaces
  124.           before the proc) will not be indexed.
  125.  
  126.      auto_reset
  127.  
  128.  
  129.  
  130. Tcl                                                             2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. library(n)            Tcl Built-In Commands
  137.  
  138.  
  139.  
  140.           Destroys all the information cached by auto_execok  and
  141.           auto_load.   This information will be re-read from disk
  142.           the next time it is needed.   Auto_reset  also  deletes
  143.           any  procedures  listed in the auto-load index, so that
  144.           fresh copies of them will be loaded the next time  that
  145.           they're used.
  146.  
  147.      parray _a_r_r_a_y_N_a_m_e
  148.           Prints on standard output the names and values  of  all
  149.           the elements in the array _a_r_r_a_y_N_a_m_e.  ArrayName must be
  150.           an array accessible to the caller of parray.  It may be
  151.           either local or global.
  152.  
  153.      unknown _c_m_d ?_a_r_g _a_r_g ...?
  154.           This procedure is  invoked  automatically  by  the  Tcl
  155.           interpreter  whenever  the  name  of  a command doesn't
  156.           exist.  The unknown procedure receives as its arguments
  157.           the name and arguments of the missing command.  Unknown  |
  158.           first calls auto_load to load  the  command.   If  this
  159.           succeeds,  then  it  executes the original command with
  160.           its original arguments.  If the  auto-load  fails  then
  161.           unknown calls auto_execok to see if there is an execut-
  162.           able file by the name _c_m_d.  If so, it invokes  the  Tcl
  163.           exec  command  with  _c_m_d and all the _a_r_g_s as arguments.
  164.           If _c_m_d can't be auto-executed, unknown checks to see if
  165.           the command was invoked at top-level and outside of any
  166.           script.  If so, then unknown takes takes two additional
  167.           steps.   First, it sees if _c_m_d has one of the following
  168.           three forms: !!, !_e_v_e_n_t, or ^_o_l_d^_n_e_w?^?.  If  so,  then
  169.           unknown  carries  out  history substitution in the same
  170.           way that csh would for these constructs.   Second,  and
  171.           last, unknown checks to see if _c_m_d is a unique abbrevi-
  172.           ation for an existing Tcl command.  If so,  it  expands
  173.           the command name and executes the command with the ori-
  174.           ginal arguments.  If none of the above efforts has been
  175.           able to execute the command, unknown generates an error
  176.           return.  If the global variable auto_noload is defined,
  177.           then  the  auto-load  step  is  skipped.  If the global
  178.           variable auto_noexec is defined then the auto-exec step
  179.           is  skipped.   Under  normal  circumstances  the return
  180.           value from unknown is the return value from the command
  181.           that was eventually executed.
  182.  
  183.  
  184. VARIABLES
  185.      The following global variables are defined or  used  by  the
  186.      procedures in the Tcl library:
  187.  
  188.      auto_execs
  189.           Used by auto_execok to record information about whether
  190.           particular commands exist as executable files.
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. library(n)            Tcl Built-In Commands
  203.  
  204.  
  205.  
  206.      auto_index
  207.           Used by auto_load to save the  index  information  read
  208.           from disk.
  209.  
  210.      auto_noexec
  211.           If set to any value, then unknown will not  attempt  to
  212.           auto-exec any commands.
  213.  
  214.      auto_noload
  215.           If set to any value, then unknown will not  attempt  to
  216.           auto-load any commands.
  217.  
  218.      auto_path
  219.           If set, then it must contain a valid  Tcl  list  giving
  220.           directories to search during auto-load operations.
  221.  
  222.      env(TCL_LIBRARY)
  223.           If set, then it specifies the location of the directory
  224.           containing  library scripts (the value of this variable
  225.           will be returned by the command info library).  If this
  226.           variable isn't set then a default value is used.
  227.  
  228.      env(TCLLIBPATH)
  229.           If set, then it must contain a valid  Tcl  list  giving
  230.           directories  to  search  during  auto-load  operations.
  231.           This variable is only used if auto_path is not defined.
  232.  
  233.      unknown_active
  234.           This variable is set by unknown to indicate that it  is
  235.           active.   It  is  used  to  detect errors where unknown
  236.           recurses on itself infinitely.  The variable  is  unset
  237.           before unknown returns.
  238.  
  239.  
  240. KEYWORDS
  241.      auto-exec, auto-load, library, unknown
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tcl                                                             4
  262.  
  263.  
  264.  
  265.